home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / Interp.3 < prev    next >
Encoding:
Text File  |  1994-12-17  |  5.3 KB  |  120 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) Interp.3 1.11 94/12/17 16:17:24
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_Interp tclc
  12. .BS
  13. .SH NAME
  14. Tcl_Interp \- client-visible fields of interpreter structures
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. typedef struct {
  20.     char *\fIresult\fR;
  21.     Tcl_FreeProc *\fIfreeProc\fR;
  22.     int \fIerrorLine\fR;
  23. } Tcl_Interp;
  24.  
  25. typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
  26. .BE
  27.  
  28. .SH DESCRIPTION
  29. .PP
  30. The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
  31. structure.  This pointer is then passed into other Tcl procedures
  32. to process commands in the interpreter and perform other operations
  33. on the interpreter.  Interpreter structures contain many many fields
  34. that are used by Tcl, but only three that may be accessed by
  35. clients:  \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR.
  36. .PP
  37. The \fIresult\fR and \fIfreeProc\fR fields are used to return
  38. results or error messages from commands.
  39. This information is returned by command procedures back to \fBTcl_Eval\fR,
  40. and by \fBTcl_Eval\fR back to its callers.
  41. The \fIresult\fR field points to the string that represents the
  42. result or error message, and the \fIfreeProc\fR field tells how
  43. to dispose of the storage for the string when it isn't needed anymore.
  44. The easiest way for command procedures to manipulate these
  45. fields is to call procedures like \fBTcl_SetResult\fR
  46. or \fBTcl_AppendResult\fR;  they
  47. will hide all the details of managing the fields.
  48. The description below is for those procedures that manipulate the
  49. fields directly.
  50. .PP
  51. Whenever a command procedure returns, it must ensure
  52. that the \fIresult\fR field of its interpreter points to the string
  53. being returned by the command.
  54. The \fIresult\fR field must always point to a valid string.
  55. If a command wishes to return no result then \fIinterp->result\fR
  56. should point to an empty string.
  57. Normally, results are assumed to be statically allocated,
  58. which means that the contents will not change before the next time
  59. \fBTcl_Eval\fR is called or some other command procedure is invoked.
  60. In this case, the \fIfreeProc\fR field must be zero.
  61. Alternatively, a command procedure may dynamically
  62. allocate its return value (e.g. using \fBmalloc\fR)
  63. and store a pointer to it in \fIinterp->result\fR.
  64. In this case, the command procedure must also set \fIinterp->freeProc\fR
  65. to the address of a procedure that can free the value (usually \fBfree\fR).
  66. If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR
  67. to free the space pointed to by \fIinterp->result\fR before it
  68. invokes the next command.
  69. If a client procedure overwrites \fIinterp->result\fR when
  70. \fIinterp->freeProc\fR is non-zero, then it is responsible for calling
  71. \fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR
  72. macro should be used for this purpose).
  73. .PP
  74. \fIFreeProc\fR should have arguments and result that match the
  75. \fBTcl_FreeProc\fR declaration above:  it receives a single
  76. argument which is a pointer to the result value to free.
  77. In most applications \fBfree\fR is the only non-zero value ever
  78. used for \fIfreeProc\fR.
  79. However, an application may store a different procedure address
  80. in \fIfreeProc\fR in order to use an alternate memory allocator
  81. or in order to do other cleanup when the result memory is freed.
  82. .PP
  83. As part of processing each command, \fBTcl_Eval\fR initializes
  84. \fIinterp->result\fR
  85. and \fIinterp->freeProc\fR just before calling the command procedure for
  86. the command.  The \fIfreeProc\fR field will be initialized to zero,
  87. and \fIinterp->result\fR will point to an empty string.  Commands that
  88. do not return any value can simply leave the fields alone.
  89. Furthermore, the empty string pointed to by \fIresult\fR is actually
  90. part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).
  91. If a command wishes to return a short string, it can simply copy
  92. it to the area pointed to by \fIinterp->result\fR.  Or, it can use
  93. the sprintf procedure to generate a short result string at the location
  94. pointed to by \fIinterp->result\fR.
  95. .PP
  96. It is a general convention in Tcl-based applications that the result
  97. of an interpreter is normally in the initialized state described
  98. in the previous paragraph.
  99. Procedures that manipulate an interpreter's result (e.g. by
  100. returning an error) will generally assume that the result
  101. has been initialized when the procedure is called.
  102. If such a procedure is to be called after the result has been
  103. changed, then \fBTcl_ResetResult\fR should be called first to
  104. reset the result to its initialized state.
  105. .PP
  106. The \fIerrorLine\fR
  107. field is valid only after \fBTcl_Eval\fR returns
  108. a \fBTCL_ERROR\fR return code.  In this situation the \fIerrorLine\fR
  109. field identifies the line number of the command being executed when
  110. the error occurred.  The line numbers are relative to the command
  111. being executed:  1 means the first line of the command passed to
  112. \fBTcl_Eval\fR, 2 means the second line, and so on.
  113. The \fIerrorLine\fR field is typically used in conjunction with
  114. \fBTcl_AddErrorInfo\fR to report information about where an error
  115. occurred.
  116. \fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR.
  117.  
  118. .SH KEYWORDS
  119. free, initialized, interpreter, malloc, result
  120.